home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Online / SpeakFreely / src / libdes / des.doc < prev    next >
Text File  |  2000-05-18  |  18KB  |  473 lines
  1. The DES library.
  2.  
  3. Please note that this library was originally written to operate with
  4. eBones, a version of Kerberos that had had encryption removed when it left
  5. the USA and then put back in.  As such there are some routines that I will
  6. advise not using but they are still in the library for historical reasons.
  7. For all calls that have an 'input' and 'output' variables, they can be the
  8. same.
  9.  
  10. This library requires the inclusion of 'des.h'.
  11.  
  12. All of the encryption functions take what is called a des_key_schedule as an 
  13. argument.  A des_key_schedule is an expanded form of the des key.
  14. A des_key is 8 bytes of odd parity, the type used to hold the key is a
  15. des_cblock.  A des_cblock is an array of 8 bytes, often in this library
  16. description I will refer to input bytes when the function specifies
  17. des_cblock's as input or output, this just means that the variable should
  18. be a multiple of 8 bytes.
  19.  
  20. The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to
  21. specify decryption.  The functions and global variable are as follows:
  22.  
  23. int des_check_key;
  24.     DES keys are supposed to be odd parity.  If this variable is set to
  25.     a non-zero value, des_set_key() will check that the key has odd
  26.     parity and is not one of the known weak DES keys.  By default this
  27.     variable is turned off;
  28.     
  29. void des_set_odd_parity(
  30. des_cblock *key );
  31.     This function takes a DES key (8 bytes) and sets the parity to odd.
  32.     
  33. int des_is_weak_key(
  34. des_cblock *key );
  35.     This function returns a non-zero value if the DES key passed is a
  36.     weak, DES key.  If it is a weak key, don't use it, try a different
  37.     one.  If you are using 'random' keys, the chances of hitting a weak
  38.     key are 1/2^52 so it is probably not worth checking for them.
  39.     
  40. int des_set_key(
  41. des_cblock *key,
  42. des_key_schedule schedule);
  43.     Des_set_key converts an 8 byte DES key into a des_key_schedule.
  44.     A des_key_schedule is an expanded form of the key which is used to
  45.     perform actual encryption.  It can be regenerated from the DES key
  46.     so it only needs to be kept when encryption or decryption is about
  47.     to occur.  Don't save or pass around des_key_schedule's since they
  48.     are CPU architecture dependent, DES keys are not.  If des_check_key
  49.     is non zero, zero is returned if the key has the wrong parity or
  50.     the key is a weak key, else 1 is returned.
  51.     
  52. int des_key_sched(
  53. des_cblock *key,
  54. des_key_schedule schedule);
  55.     An alternative name for des_set_key().
  56.  
  57. int des_rw_mode;        /* defaults to DES_PCBC_MODE */
  58.     This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default).
  59.     This specifies the function to use in the enc_read() and enc_write()
  60.     functions.
  61.  
  62. void des_encrypt(
  63. unsigned long *data,
  64. des_key_schedule ks,
  65. int enc);
  66.     This is the DES encryption function that gets called by just about
  67.     every other DES routine in the library.  You should not use this
  68.     function except to implement 'modes' of DES.  I say this because the
  69.     functions that call this routine do the conversion from 'char *' to
  70.     long, and this needs to be done to make sure 'non-aligned' memory
  71.     access do not occur.  The characters are loaded 'little endian',
  72.     have a look at my source code for more details on how I use this
  73.     function.
  74.     Data is a pointer to 2 unsigned long's and ks is the
  75.     des_key_schedule to use.  enc, is non zero specifies encryption,
  76.     zero if decryption.
  77.  
  78. void des_encrypt2(
  79. unsigned long *data,
  80. des_key_schedule ks,
  81. int enc);
  82.     This functions is the same as des_encrypt() except that the DES
  83.     initial permutation (IP) and final permutation (FP) have been left
  84.     out.  As for des_encrypt(), you should not use this function.
  85.     It is used by the routines in my library that implement triple DES.
  86.     IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same
  87.     as des_encrypt() des_encrypt() des_encrypt() except faster :-).
  88.  
  89. void des_ecb_encrypt(
  90. des_cblock *input,
  91. des_cblock *output,
  92. des_key_schedule ks,
  93. int enc);
  94.     This is the basic Electronic Code Book form of DES, the most basic
  95.     form.  Input is encrypted into output using the key represented by
  96.     ks.  If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise
  97.     decryption occurs.  Input is 8 bytes long and output is 8 bytes.
  98.     (the des_cblock structure is 8 chars).
  99.     
  100. void des_ecb3_encrypt(
  101. des_cblock *input,
  102. des_cblock *output,
  103. des_key_schedule ks1,
  104. des_key_schedule ks2,
  105. des_key_schedule ks3,
  106. int enc);
  107.     This is the 3 key EDE mode of ECB DES.  What this means is that 
  108.     the 8 bytes of input is encrypted with ks1, decrypted with ks2 and
  109.     then encrypted again with ks3, before being put into output;
  110.     C=E(ks3,D(ks2,E(ks1,M))).  There is a macro, des_ecb2_encrypt()
  111.     that only takes 2 des_key_schedules that implements,
  112.     C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1.
  113.     
  114. void des_cbc_encrypt(
  115. des_cblock *input,
  116. des_cblock *output,
  117. long length,
  118. des_key_schedule ks,
  119. des_cblock *ivec,
  120. int enc);
  121.     This routine implements DES in Cipher Block Chaining mode.
  122.     Input, which should be a multiple of 8 bytes is encrypted
  123.     (or decrypted) to output which will also be a multiple of 8 bytes.
  124.     The number of bytes is in length (and from what I've said above,
  125.     should be a multiple of 8).  If length is not a multiple of 8, I'm
  126.     not being held responsible :-).  ivec is the initialisation vector.
  127.     This function does not modify this variable.  To correctly implement
  128.     cbc mode, you need to do one of 2 things; copy the last 8 bytes of
  129.     cipher text for use as the next ivec in your application,
  130.     or use des_ncbc_encrypt(). 
  131.     Only this routine has this problem with updating the ivec, all
  132.     other routines that are implementing cbc mode update ivec.
  133.     
  134. void des_ncbc_encrypt(
  135. des_cblock *input,
  136. des_cblock *output,
  137. long length,
  138. des_key_schedule sk,
  139. des_cblock *ivec,
  140. int enc);
  141.     For historical reasons, des_cbc_encrypt() did not update the
  142.     ivec with the value requires so that subsequent calls to
  143.     des_cbc_encrypt() would 'chain'.  This was needed so that the same
  144.     'length' values would not need to be used when decrypting.
  145.     des_ncbc_encrypt() does the right thing.  It is the same as
  146.     des_cbc_encrypt accept that ivec is updates with the correct value
  147.     to pass in subsequent calls to des_ncbc_encrypt().  I advise using
  148.     des_ncbc_encrypt() instead of des_cbc_encrypt();
  149.     
  150. void des_3cbc_encrypt(
  151. des_cblock *input,
  152. des_cblock *output,
  153. long length,
  154. des_key_schedule sk1,
  155. des_key_schedule sk2,
  156. des_cblock *ivec1,
  157. des_cblock *ivec2,
  158. int enc);
  159.     This function is flawed, do not use it.  I have left it in the
  160.     library because it is used in my des(1) program and will function
  161.     correctly when used by des(1).  If I removed the function, people
  162.     could end up unable to decrypt files.
  163.     This routine implements outer triple cbc encryption using 2 ks and
  164.     2 ivec's.  Use des_ede2_cbc_encrypt() instead.
  165.     
  166. void des_ede3_cbc_encrypt(
  167. des_cblock *input,
  168. des_cblock *output, 
  169. long length,
  170. des_key_schedule ks1,
  171. des_key_schedule ks2, 
  172. des_key_schedule ks3, 
  173. des_cblock *ivec,
  174. int enc);
  175.     This function implements inner triple CBC DES encryption with 3
  176.     keys.  What this means is that each 'DES' operation
  177.     inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))).
  178.     Again, this is cbc mode so an ivec is requires.
  179.     This mode is used by SSL.
  180.     There is also a des_ede2_cbc_encrypt() that only uses 2
  181.     des_key_schedule's, the first being reused for the final
  182.     encryption.  C=E(ks1,D(ks2,E(ks1,M))).  This form of triple DES
  183.     is used by the RSAref library.
  184.     
  185. void des_pcbc_encrypt(
  186. des_cblock *input,
  187. des_cblock *output,
  188. long length,
  189. des_key_schedule ks,
  190. des_cblock *ivec,
  191. int enc);
  192.     This is Propagating Cipher Block Chaining mode of DES.  It is used
  193.     by Kerberos v4.  It's parameters are the same as des_ncbc_encrypt().
  194.     
  195. void des_cfb_encrypt(
  196. unsigned char *in,
  197. unsigned char *out,
  198. int numbits,
  199. long length,
  200. des_key_schedule ks,
  201. des_cblock *ivec,
  202. int enc);
  203.     Cipher Feedback Back mode of DES.  This implementation 'feeds back'
  204.     in numbit blocks.  The input (and output) is in multiples of numbits
  205.     bits.  numbits needs to be a multiple of 8 bits.  Length is the
  206.     number of bytes input.
  207.     
  208. void des_cfb64_encrypt(
  209. unsigned char *in,
  210. unsigned char *out,
  211. long length,
  212. des_key_schedule ks,
  213. des_cblock *ivec,
  214. int *num,
  215. int enc);
  216.     This is one of the more useful functions in this DES library, it
  217.     implements CFB mode of DES with 64bit feedback.  Why is this
  218.     useful you ask?  Because this routine will allow you to encrypt an
  219.     arbitrary number of bytes, no 8 byte padding.  Each call to this
  220.     routine will encrypt the input bytes to output and then update ivec
  221.     and num.  num contains 'how far' we are though ivec.  If this does
  222.     not make much sense, read more about cfb mode of DES :-).
  223.     
  224. void des_ede3_cfb64_encrypt(
  225. unsigned char *in,
  226. unsigned char *out,
  227. long length,
  228. des_key_schedule ks1,
  229. des_key_schedule ks2,
  230. des_key_schedule ks3,
  231. des_cblock *ivec,
  232. int *num,
  233. int enc);
  234.     Same as des_cfb64_encrypt() accept that the DES operation is
  235.     triple DES.  As usual, there is a macro for
  236.     des_ede2_cfb64_encrypt() which reuses ks1.
  237.  
  238. void des_ofb_encrypt(
  239. unsigned char *in,
  240. unsigned char *out,
  241. int numbits,
  242. long length,
  243. des_key_schedule ks,
  244. des_cblock *ivec);
  245.     This is a implementation of Output Feed Back mode of DES.  It is
  246.     the same as des_cfb_encrypt() in that numbits is the size of the
  247.     units dealt with during input and output (in bits).
  248.     
  249. void des_ofb64_encrypt(
  250. unsigned char *in,
  251. unsigned char *out,
  252. long length,
  253. des_key_schedule ks,
  254. des_cblock *ivec,
  255. int *num);
  256.     The same as des_cfb64_encrypt() except that it is Output Feed Back
  257.     mode.
  258.  
  259. void des_ede3_ofb64_encrypt(
  260. unsigned char *in,
  261. unsigned char *out,
  262. long length,
  263. des_key_schedule ks1,
  264. des_key_schedule ks2,
  265. des_key_schedule ks3,
  266. des_cblock *ivec,
  267. int *num);
  268.     Same as des_ofb64_encrypt() accept that the DES operation is
  269.     triple DES.  As usual, there is a macro for
  270.     des_ede2_ofb64_encrypt() which reuses ks1.
  271.  
  272. int des_read_pw_string(
  273. char *buf,
  274. int length,
  275. char *prompt,
  276. int verify);
  277.     This routine is used to get a password from the terminal with echo
  278.     turned off.  Buf is where the string will end up and length is the
  279.     size of buf.  Prompt is a string presented to the 'user' and if
  280.     verify is set, the key is asked for twice and unless the 2 copies
  281.     match, an error is returned.  A return code of -1 indicates a
  282.     system error, 1 failure due to use interaction, and 0 is success.
  283.  
  284. unsigned long des_cbc_cksum(
  285. des_cblock *input,
  286. des_cblock *output,
  287. long length,
  288. des_key_schedule ks,
  289. des_cblock *ivec);
  290.     This function produces an 8 byte checksum from input that it puts in
  291.     output and returns the last 4 bytes as a long.  The checksum is
  292.     generated via cbc mode of DES in which only the last 8 byes are
  293.     kept.  I would recommend not using this function but instead using
  294.     the EVP_Digest routines, or at least using MD5 or SHA.  This
  295.     function is used by Kerberos v4 so that is why it stays in the
  296.     library.
  297.     
  298. char *crypt(
  299. const char *buf,
  300. const char *salt);
  301.     This is my fast version of the unix crypt(3) function.  This version
  302.     takes only a small amount of space relative to other fast
  303.     crypt() implementations.
  304.  
  305. void des_string_to_key(
  306. char *str,
  307. des_cblock *key);
  308.     This function takes str and converts it into a DES key.  I would
  309.     recommend using MD5 instead and use the first 8 bytes of output.
  310.     When I wrote the first version of these routines back in 1990, MD5
  311.     did not exist but I feel these routines are still sound.  This
  312.     routines is compatible with the one in MIT's libdes.
  313.     
  314. void des_string_to_2keys(
  315. char *str,
  316. des_cblock *key1,
  317. des_cblock *key2);
  318.     This function takes str and converts it into 2 DES keys.
  319.     I would recommend using MD5 and using the 16 bytes as the 2 keys.
  320.     I have nothing against these 2 'string_to_key' routines, it's just
  321.     that if you say that your encryption key is generated by using the
  322.     16 bytes of an MD5 hash, every-one knows how you generated your
  323.     keys.
  324.  
  325. int des_read_password(
  326. des_cblock *key,
  327. char *prompt,
  328. int verify);
  329.     This routine combines des_read_pw_string() with des_string_to_key().
  330.  
  331. int des_read_2passwords(
  332. des_cblock *key1,
  333. des_cblock *key2,
  334. char *prompt,
  335. int verify);
  336.     This routine combines des_read_pw_string() with des_string_to_2key().
  337.  
  338. void des_random_seed(
  339. des_cblock key);
  340.     This routine sets a starting point for des_random_key().
  341.     
  342. void des_random_key(
  343. des_cblock ret);
  344.     This function return a random key.  Make sure to 'seed' the random
  345.     number generator (with des_random_seed()) before using this function.
  346.     I personally now use a MD5 based random number system.
  347.  
  348. int des_enc_read(
  349. int fd,
  350. char *buf,
  351. int len,
  352. des_key_schedule ks,
  353. des_cblock *iv);
  354.     This function will write to a file descriptor the encrypted data
  355.     from buf.  This data will be preceded by a 4 byte 'byte count' and
  356.     will be padded out to 8 bytes.  The encryption is either CBC of
  357.     PCBC depending on the value of des_rw_mode.  If it is DES_PCBC_MODE,
  358.     pcbc is used, if DES_CBC_MODE, cbc is used.  The default is to use
  359.     DES_PCBC_MODE.
  360.  
  361. int des_enc_write(
  362. int fd,
  363. char *buf,
  364. int len,
  365. des_key_schedule ks,
  366. des_cblock *iv);
  367.     This routines read stuff written by des_enc_read() and decrypts it.
  368.     I have used these routines quite a lot but I don't believe they are
  369.     suitable for non-blocking io.  If you are after a full
  370.     authentication/encryption over networks, have a look at SSL instead.
  371.  
  372. unsigned long des_quad_cksum(
  373. des_cblock *input,
  374. des_cblock *output,
  375. long length,
  376. int out_count,
  377. des_cblock *seed);
  378.     This is a function from Kerberos v4 that is not anything to do with
  379.     DES but was needed.  It is a cksum that is quicker to generate than
  380.     des_cbc_cksum();  I personally would use MD5 routines now.
  381. =====
  382. Modes of DES
  383. Quite a bit of the following information has been taken from
  384.     AS 2805.5.2
  385.     Australian Standard
  386.     Electronic funds transfer - Requirements for interfaces,
  387.     Part 5.2: Modes of operation for an n-bit block cipher algorithm
  388.     Appendix A
  389.  
  390. There are several different modes in which DES can be used, they are
  391. as follows.
  392.  
  393. Electronic Codebook Mode (ECB) (des_ecb_encrypt())
  394. - 64 bits are enciphered at a time.
  395. - The order of the blocks can be rearranged without detection.
  396. - The same plaintext block always produces the same ciphertext block
  397.   (for the same key) making it vulnerable to a 'dictionary attack'.
  398. - An error will only affect one ciphertext block.
  399.  
  400. Cipher Block Chaining Mode (CBC) (des_cbc_encrypt())
  401. - a multiple of 64 bits are enciphered at a time.
  402. - The CBC mode produces the same ciphertext whenever the same
  403.   plaintext is encrypted using the same key and starting variable.
  404. - The chaining operation makes the ciphertext blocks dependent on the
  405.   current and all preceding plaintext blocks and therefore blocks can not
  406.   be rearranged.
  407. - The use of different starting variables prevents the same plaintext
  408.   enciphering to the same ciphertext.
  409. - An error will affect the current and the following ciphertext blocks.
  410.  
  411. Cipher Feedback Mode (CFB) (des_cfb_encrypt())
  412. - a number of bits (j) <= 64 are enciphered at a time.
  413. - The CFB mode produces the same ciphertext whenever the same
  414.   plaintext is encrypted using the same key and starting variable.
  415. - The chaining operation makes the ciphertext variables dependent on the
  416.   current and all preceding variables and therefore j-bit variables are
  417.   chained together and can not be rearranged.
  418. - The use of different starting variables prevents the same plaintext
  419.   enciphering to the same ciphertext.
  420. - The strength of the CFB mode depends on the size of k (maximal if
  421.   j == k).  In my implementation this is always the case.
  422. - Selection of a small value for j will require more cycles through
  423.   the encipherment algorithm per unit of plaintext and thus cause
  424.   greater processing overheads.
  425. - Only multiples of j bits can be enciphered.
  426. - An error will affect the current and the following ciphertext variables.
  427.  
  428. Output Feedback Mode (OFB) (des_ofb_encrypt())
  429. - a number of bits (j) <= 64 are enciphered at a time.
  430. - The OFB mode produces the same ciphertext whenever the same
  431.   plaintext enciphered using the same key and starting variable.  More
  432.   over, in the OFB mode the same key stream is produced when the same
  433.   key and start variable are used.  Consequently, for security reasons
  434.   a specific start variable should be used only once for a given key.
  435. - The absence of chaining makes the OFB more vulnerable to specific attacks.
  436. - The use of different start variables values prevents the same
  437.   plaintext enciphering to the same ciphertext, by producing different
  438.   key streams.
  439. - Selection of a small value for j will require more cycles through
  440.   the encipherment algorithm per unit of plaintext and thus cause
  441.   greater processing overheads.
  442. - Only multiples of j bits can be enciphered.
  443. - OFB mode of operation does not extend ciphertext errors in the
  444.   resultant plaintext output.  Every bit error in the ciphertext causes
  445.   only one bit to be in error in the deciphered plaintext.
  446. - OFB mode is not self-synchronising.  If the two operation of
  447.   encipherment and decipherment get out of synchronism, the system needs
  448.   to be re-initialised.
  449. - Each re-initialisation should use a value of the start variable
  450.  different from the start variable values used before with the same
  451.  key.  The reason for this is that an identical bit stream would be
  452.  produced each time from the same parameters.  This would be
  453.  susceptible to a ' known plaintext' attack.
  454.  
  455. Triple ECB Mode (des_ecb3_encrypt())
  456. - Encrypt with key1, decrypt with key2 and encrypt with key3 again.
  457. - As for ECB encryption but increases the key length to 168 bits.
  458.   There are theoretic attacks that can be used that make the effective
  459.   key length 112 bits, but this attack also requires 2^56 blocks of
  460.   memory, not very likely, even for the NSA.
  461. - If both keys are the same it is equivalent to encrypting once with
  462.   just one key.
  463. - If the first and last key are the same, the key length is 112 bits.
  464.   There are attacks that could reduce the key space to 55 bit's but it
  465.   requires 2^56 blocks of memory.
  466. - If all 3 keys are the same, this is effectively the same as normal
  467.   ecb mode.
  468.  
  469. Triple CBC Mode (des_ede3_cbc_encrypt())
  470. - Encrypt with key1, decrypt with key2 and then encrypt with key3.
  471. - As for CBC encryption but increases the key length to 168 bits with
  472.   the same restrictions as for triple ecb mode.
  473.